<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
    <meta http-equiv="Content-Type"
          content="text/html; charset=iso-8859-1">
    <meta name="GENERATOR"
          content="Mozilla/4.61 [en] (X11; U; SunOS 5.8 sun4u) [Netscape]">
    <title>JGroups 3.x Installation</title>
    <link rel="STYLESHEET" href="../user.css">
</head>
<body alink="#ff0000" bgcolor="#ffffff" link="#0000ee" text="#000000"
      vlink="#551a8b">
<comment> </comment>
<h1> Installation Instructions for JGroups<br>
</h1>
JGroups is shipped as a single JAR: <b>jgroups-3.x.y.jar</b>.
<br>
<h3> Requirements</h3>
<ul>
    <li>JGroups 3.x requires JDK 6 or higher.<br></li>
    <li>There is no JNI code present so JGroups should run on all platforms.</li>
</ul>
<h3>Installing the binary distribution</h3>
The binary version consists of jgroups-3.x.y.jar: the JGroups library including some demos, test code and sample
configuration files. Place jgroups-3.x.y.jar somewhere on your <b>CLASSPATH</b>, and you're ready to start using JGroups.
<br>

<h3> Testing your Setup</h3>
To see whether your system can find the JGroups classes, execute the following command:
<pre>java org.jgroups.Version<br></pre>
<br>
or<br>
<b><br>
    java -jar jgroups-all.jar<br>
    <br>
</b><br>
You should see the following output (more or less) if the class is found:
<pre><br>Version:      3.0.0.Final<br></pre>


<h3>Running the performance tests</h3>
<pre><br></pre>
By default, we're running 2 senders with 10000 1K messages each, to do this, execute the following in 2 shells:<br>
<br>
<pre> ./jgroups.sh tests.perf.Test -config ./config.txt  -props ./udp.xml -sender</pre>
<br>
You should see output like the following in both shells:<br>
<br>
<pre>-- results:

linux-34003 (myself):
num_msgs_expected=2000000, num_msgs_received=2000000 (loss rate=0.0%), received=2GB, time=13158ms, msgs/sec=151998.78, throughput=152MB

linux-15721:
num_msgs_expected=2000000, num_msgs_received=2000000 (loss rate=0.0%), received=2GB, time=13073ms, msgs/sec=152987.07, throughput=152.99MB

combined: 152492.93 msgs/sec averaged over all receivers (throughput=152.49MB/sec)


-- results:

linux-34003 (myself):
num_msgs_expected=2000000, num_msgs_received=2000000 (loss rate=0.0%), received=2GB, time=13158ms, msgs/sec=151998.78, throughput=152MB

linux-15721:
num_msgs_expected=2000000, num_msgs_received=2000000 (loss rate=0.0%), received=2GB, time=13073ms, msgs/sec=152987.07, throughput=152.99MB

combined: 152492.93 msgs/sec averaged over all receivers (throughput=152.49MB/sec)
</pre>
<br>

<h3> Running a Demo Program</h3>
To test whether JGroups works okay on your machine, run (assuming jgroups-3.x.y.jar is on the classpath)
<pre><b>java -Djava.net.preferIPv4Stack=true org.jgroups.demos.Draw</b></pre> twice.

2 whiteboard windows should appear, and both window title bars should show 2. This means that the two instances
found each other and formed a cluster.

<p>When drawing in one window, the second instance should also be updated. As the default group transport uses
    IP multicast, make sure that - if you want to start the 2 instances in different subnets - IP multicast
    is enabled. If this is not the case, the 2 instances won't 'find' each other and the sample won't work. </p>
<p>You can change the properties of the demo to for example use a different transport if multicast doesn't work
    (it should always work on the same machine). For example, to use udp.xml, execute:</p>
<pre>java -Djava.net.preferIPv4Stack=true org.jgroups.demos.Draw -props ./udp.xml</pre>
<p>&nbsp; </p>
<h3> Using IP Multicasting without a network connection</h3>
Sometimes there isn't a network connection (e.g. DSL modem is down), or
we want to multicast only on the local machine. For this the loopback
interface (typically lo) can be configured, e.g.
<pre><b>route add -net 224.0.0.0 netmask 224.0.0.0 dev lo</b></pre>
This means that all traffic directed to the 224.0.0.0 network will
be sent to the loopback interface, which means it doesn't need any
network to be running. Note that the 224.0.0.0 network is a placeholder
for all multicast addresses in most UNIX implementations: it will catch
<b>all</b> multicast traffic. This is an undocumented feature of
/sbin/route and may not work across all UNIX flavors. The above
instructions may also work for Windows systems, but this hasn't been
tested. Note that not all systems allow multicast traffic to use the
loopback interface.
<p>Typical home networks have a gateway/firewall with 2 NICs: the first
    (eth0) is connected to the outside world (Internet Service Provider),
    the second (eth1) to the internal network, with the gateway
    firewalling/masquerading traffic between the internal and external
    networks. If no route for multicast traffic is added, the default will
    be to use the fdefault gateway, which will typically direct the
    multicast traffic towards the ISP. To prevent
    this (e.g. ISP drops multicast traffic, or latency is too high), we
    recommend to add a route for multicast traffic which goes to the
    internal network
    (e.g. eth1). <br>
    &nbsp; </p>

<h3>The instances don't find each other !&nbsp;</h3>
<p>In this case we can enable the sender and receiver test to use all
    available interfaces for sending and receiving. One of them will
    certainly
    be the right one... Start the receiver as follows:</p>
<pre><b>java org.jgroups.tests.McastReceiverTest -mcast_addr 228.8.8.8</b><br></pre>
<p>The multicast receiver uses JDK functionality to list <i><b>all
    available network interfaces and bind to all of them</b></i> (including
    the loopback interface). This means that whichever interface a packet
    comes in on, we
    will receive it.<br>
    Now start the sender:<br>
</p>
<pre><b>java org.jgroups.tests.McastSenderTest -mcast_addr 228.8.8.8</b><br></pre>
<h3></h3>
<p>The sender will also determine the available network interfaces and
    send each packet over all interfaces.</p>
<p>This test can be used to find out which network interface to bind to
    when previously no packets were received. E.g. when you see the
    following output in the receiver:</p>
<pre>bash-2.03$ <b>java org.jgroups.tests.McastReceiverTest -mcast_addr 228.8.8.8 -bind_addr 192.168.168.4</b><br>Socket=0.0.0.0/0.0.0.0:5555, bind interface=/192.168.168.4<br>dd [sender=192.168.168.4:5555]<br>dd [sender=192.168.168.1:5555]<br>dd [sender=192.168.168.2:5555]</pre>
<p>you know that you can bind to any of the 192.168.168.{1,2,4}
    interfaces to receive your multicast packets. In this case you would
    need to modify
    your protocol spec to include bind_addr=192.168.168.2 in UDP, e.g. <b>"UDP(mcast_addr=228.8.8.8;bind_addr=192.168.168.2):..."</b>
    .</p>
<p><br>
</p>
<p>Alternatively you can use McastDiscovery.
    Start this program simultaneously on multiple machines. Binding to all
    available interfaces, this program tries to discover what other members
    are available in a network and determines which interfaces should be
    used by UDP. After some time (e.g. 30 seconds), press &lt;enter&gt; on
    each program. The program will then list the interfaces which can be
    used to bind to. There may be
    one or multiple interfaces. When there are multiple interfaces listed,
    take
    the one with the highest number of responses (at the top of the list).
    The
    UDP protocol spec can then be changed to explicitly bind to that
    interface,
    e.g.<br>
</p>
<p><b>"UDP(bind_addr=&lt;interface&gt;;...)"</b><br>
</p>
<p><br>
</p>
<h3>Problems with IPv6</h3>
<p>Another source of problems might be the use of IPv6, and/or misconfiguration
    of <b>/etc/hosts</b>. If you communicate between an IPv4 and an IPv6 host,
    and they are not able to find each other, try the <b>java.net.preferIP4Stack=true</b>
    property, e.g.<br>
</p>
<p><b>java -Djava.net.preferIPv4Stack=true org.jgroups.demos.Draw -props file:c:\\udp.xml<br>
</b></p>
<p>JDK 6 uses IPv6 by default, although is has a dual stack, that is, it also supports IPv4. <a
            href="http://java.sun.com/j2se/1.4/docs/guide/net/ipv6_guide/">Here's </a>more
    details on the subject.<br>
</p>
<p><br>
    If you want to use IPv6, omit the -Djava.net.preferIPv4Stack=true or force use of IPv6 by using
    -Djava.net.preferIPv6Addresses=true
</p>
<h3> I have discovered a bug !</h3>
If you think that you discovered a bug, submit a bug report on <a
        href="http://jira.jboss.com/jira/browse/JGRP">JIRA</a> or send email
to javagroups-developers if you're unsure about it. Please include the
following information:
<ul>
    <li> Version of JGroups (j<tt>ava org.jgroups.Version</tt>)</li>
    <li> Platform (e.g. Solaris 8)</li>
    <li> Version of JDK (e.g. JDK 1.4.2_07)</li>
    <li> Stack trace. Use kill -3 PID on UNIX systems or CTRL-BREAK on
        windows machines</li>
    <li> Small program that reproduces the bug</li>
</ul>
<br>
&nbsp; <br>
&nbsp; <br>
<br>
<br>
<br>
<br>
</body>
</html>
